Graphics Plus/Graphics Plus.iso/amiga/opalvisn/lsidocs.lha/LoaderSaver.doc

Text File | 1993-07-27 | 25.9 KB | 630 lines

          Loader Saver documentation (Draft)


            INTRODUCTION

OpalPaint's  Loader  and  Saver modules are implemented in a different manor
than  the  Drawing Mode, Artist Tool, and Paper Type modules.  Communication
between  the  Loader Saver modules and OpalPaint is handled exlusively using
Exec  Messages.   This interlace will be known as the Loader Saver Interface
(LSI).

This  interface has been designed to decouple as much as possible the loader
or  saver  program  from  OpalPaint  itself,  by  doing  this  the module is
available  for  use  by  not  only  OpalPaint  but  any  other program which
understands  the  message  passing  format.   This includes the Opal.Library
which  provides  alot  of  compatibility.   As  every  other  program except
OpalPaint  uses  the  library's load and save functions this gives automatic
compatibility  with OpalHotKey, MakeAnim24, OpalPresents!, Show24 and the PD
programs which are now starting to appear.

As  the  interface is purely a transparent way of passing Image data between
the  two  programs  the LSI can be used for many different types of modules,
for  example a module to print the current image could be written as a saver
module  and  a  module  to  scan  an  image from a flat bed scanner could be
written as a loader module.

The  opal.library  is  used  as  the  clearing house for the LSI modules.  A
module  must  make  itself  available  for  use  by  calling an opal.library
function to have itself added to the current list of modules.  Likewise when
an  application  such  as  OpalPaint wishes to perform a save or load it can
call  an  opal.library  function  to  get  the  currently  available list of
modules.

For  a  particular  file  format, a seperate loader and saver module must be
written, or alternatively only one of these can be implemented.


            INITIALISING LSI MODULES

The LSIModules must reside in the correct directories, that is:

    OpalPaint:Savers     - For Saver modules.
    OpalPaint:Loaders    - For Loader modules.

also, the modules must have the correct file name extensions, that is:

    .saver            - For Saver modules.
    .loader            - For Loader modules.

The  modules  are  initialised  into the system by executing the InstallLSI
command,  this command scans through the above directories and executes all
the  programs  with the correct extensions.  This command would normally be
executed  in  the  s:user-startup or via the WBStartup.  The InstallLSI and
RemoveLSI  programs  accept  a  'verbose'  parameter which will display all
modules installed and removed from the system.



             THE LOADER SAVER INTERFACE

The  application  performing  the  save  or  load  will  be  called the host
application.   The  communication between the host and LSI module is handled
using Exec messages, the actual message structure is called an LSIMessage an
has the following format:


struct LSIMessage
    { struct Message lsi_Node;    /* Standard Message Node    */
      ULONG lsi_Type;        /* Command Type            */
      ULONG lsi_SubType;        /* Command SubType        */
      ULONG lsi_Flags;        /* General Flags        */
      SHORT lsi_X;            /* Horizontal pixel offset    */
      SHORT lsi_Y;            /* Vertical pixel offset    */
      SHORT lsi_Width;        /* Image Width            */
      SHORT lsi_Height;        /* Image Height            */
      SHORT lsi_Depth;        /* Image Depth            */
      SHORT lsi_Resolution;        /* Opal image resolution flags    */
      UBYTE *lsi_Planes[24];    /* BitPlane pointers        */
      ULONG lsi_Result;        /* Command Result        */
      BPTR    lsi_File;        /* File handle            */
      char    *lsi_FileName;        /* File name being loaded    */
      struct OpalScreen *lsi_OScrn;    /* OpalScreen as Source or Dest */
      LONG    lsi_DataLength;        /* Misc data length        */
      APTR    lsi_Address;        /* Misc pointer         */
    };

   lsi_Node
    This is a standard Exec message.

   lsi_Type
    This field defines the type of command to be performed, this command
    could be from the host to the module or module to host. Typical
    commands form the host would be 'Save Image','load Image','Check file
    format' and typical commands from the module to the host would be
    'Get Image Data', 'Set Palette'.

   lsi_SubType
    This field is used as a qualifier to the Type command. This is currently
    only used for the OVCMD_GETDATA and OVCMD_SENDDATA commands to specify
    the data format of image data being passed (for example BitPlanes,
    RGB or interleaved bitmap).

   lsi_Flags
    This is a set of flags which are specific to the current command
    (lsi_Type) being performed.

   lsi_X, lsi_Y
    This is used to specify the destination or source pixel location for
    image data in the OVCMD_GETDATA and OVCMD_SENDDATA. Note that for
    some data formats the 'X' location will not be valid.

   lsi_Width,lsi_Height
    This is used to specify the rectangular section of image data for
    the OVCMD_GETDATA and OVCMD_SENDDATA.

    These fields will also give the size of the image in the OVCMD_SAVEIMAGE
    command or should be set to the image size for the OVCMD_FORMATCHECK
    command.

   lsi_Depth
    This field will contain the depth of the image in the OVCMD_SAVEIMAGE
    command or should be set to the image depth for the OVCMD_FORMATCHECK
    command.

   lsi_Resolution
    This field will contain the resolution of the image as defined in
    opallib.h (i.e HIRES24, ILACE24 etc). This will be valid in the
    OVCMD_SAVEIMAGE field or should be set to the image depth for the
    OVCMD_FORMATCHECK command.

   lsi_Planes
    This array will contain pointers to either an initialised source
    image buffer for the OVCMD_SENDDATA command or empty buffers large
    enough to hold the image data for the OVCMD_GETDATA command. The
    number of pointers that need to be initialised will vary depending
    on the format of the image data.

   lsi_Result
    This field will hold the return values of commands when appropriate.

   lsi_file
    This field will hold the Dos filehandle for the image being loaded
    this is only valid for loads. When performing a save you must
    open the file named by lsi_FileName.

   lsi_FileName
    This is the full filename (including path) of the image being
    saved or loaded.

   lsi_OScrn
    This is a pointer to the OpalScreen structure describing the
    image that is being saved. Only use this structure if absolutely
    necessary.

   lsi_Address
    This is a general purpose pointer which is used by some commands.

   lsi_DataLength
    When lsi_Address is used as a pointer to an array or buffer, this
    field contains the length of the buffer itself.


To  issue  a  command  to  the  host, it requires a standard PutMsg(),
WaitPort(), GetMsg() sequence. To simplify this the LSICmd() macro
defined in LoadSave.h can be used. The format is:

   LSICmd (struct MsgPort *HostPort, struct MsgPort *ModulePort,
         struct LSIMessage *Command)



            SAVER MODULES

When  a  Saver module initialises itself it must create a message port
which  will  be used to communicate with the host program.  The naming
convention  for  this  port will include a brief name of the format or
purpose  of  the  module suffixed with "_Saver" some examples would be
"Tiff_Saver", "Epson123_Saver".

Once  this  message port has been created you must add yourself to the
current  list  of  active  saver modules, to do this you must open the
opal.library and issue the following command:

    AddOVSaver (SaverName,SaverPort,Flags)

'SaverName' will normally be the portname without the "_Saver" suffix.
This  name  will  be used to identify the saver both internally within
applications  and  also  to  the user in programs like OpalPaint which
give a list of the currently available saver modules.

'SaverPort' is a pointer to the message port created earlier.

'Flags' include the following flags:

   OVSF_ALLOWIMAGE
    Module is capable of saving the image data.

   OVSF_ALLOWSTENCIL
    Module is capable of saving a 1 bitplane stencil.

   OVSF_ALLOWALPHA
    Module is capable of saving 8bit alpha channel data.

   OVSF_NEEDFILENAME
    Module requires a filename to perform the save. This is useful
    for modules such as printer output which do not require a
    filename and hence the user will not see a filerequester in
    OpalPaint.


Once  the module has been added to the system, it should then wait for
messages  to  arrive  at  it's message port.  When an external program
attempts  to  perform  a  save  using  your  module you will receive a
OVCMD_SAVEIMAGE  LSIMessage  at  your port.  This message will contain
the  size  of  the  image  in  pixels in lsi_Width and lsi_Height, the
bitplane  depth  of the image in lsi_Depth as well as the filename for
the  resulting  file in lsi_FileName (if the OVSF_NEEDFILENAME flag is
set for that module).  The image components that need to be saved will
be defined by lsi_Flags, these flags are LSIF_IMAGEDATA,LSIF_ALPHA and
LSIF_STENCIL.

Note,  before  you  wait for messages at your message port, you should
close  opal.library  if  you  fail  to  do  so,  the library cannot be
expunged from memory.

While  your module is inactive, one of 3 possible messages can arrive,
OVCMD_SAVEIMAGE  which will start the save sequence, and OVCMD_EXPUNGE
which  tells the module the remove itself from memory.  If you receive
an  OVCMD_EXPUNGE  you  should remove yourself from the active list of
saver  modules  using  RemOVSaver() opal.library function, cleanup all
resources and exit.

The  third  command  is  OVCMD_PARAMETERS this is used to set specific
parameters  for  your  module,  the  parameters  will be a text string
pointed  to  by lsi_Address.  This is a single text string so that the
parameters  can  be  passed  via ARexx or any other application.  This
would  for  instance  be  called after the following Arexx command was
issued to OpalPaint:

    Saver JPEG Quality=75

The  string 'Quality=75' would then be passed to the JPEG saver module
via  the  OVCMD_SETPARAMTERS command.  The format of the parameters is
completely  up to your own requirements, you should of course make the
allowable parameters known in the documentation for your module.

Once the OVCMD_SAVEIMAGE message has been received you must then reply
to this message and perform the save.

The  Flags  in  the  OVCMD_SAVEIMAGE  message defines which components
should  be  saved,  this  could  be  LSIF_IMAGEDATA,  LSIF_STENCIL  or
LSIF_ALPHA,  these  flags  should  effect which data types you request
using OVCMD_GETDATA.

To  save the image you first need to find the message port of the Host
application  performing  the  save,  this  port  will  always be named
"OVSaver_Port"  which  is  defined  in the header file as OVSAVERPORT.
Once  this port has been found you can then issue commands back to the
host  so  that  the actual image data can be retrieved.  The following
commands are currently supported:


   OVCMD_GETDATA
    Get image data from the application. lsi_X, lsi_Y denotes the
    position within the image where you wish to get the image data
    from (i.e. Top-Left), and lsi_Width and lsi_Height defines the
    size of the data that you require. Note that some data formats
    do not support a non-zero x or a width less than the image width.

    The actual format of the image data is specified in lsi_SubType
    and can be any of the following formats:

       OVDF_PLANAR
        Standard bitplane format. lsi_Planes must contain pointers
        to enough bitplanes to hold the data, the depth of the original
        image is given in lsi_Depth in the OVCMD_SAVEIMAGE message.
        In this format only lsi_Y and lsi_Height are valid, pixel
        positioning of data is not allowed.

       OVDF_RGB
        This format will return 3 byte planes of Red, Green and Blue.
        The first 3 entries in lsi_Planes must point to buffers
        large enough to hold lsi_Width*lsi_Height bytes.

       OVDF_GREY
        This format will return grey scale image data. Each pixel
        will be returned as a single byte giving 8bit grey scale.
        The first entry in lsi_Planes must point to a buffer large
        enough to hold lsi_Width*lsi_Height bytes.

       OVDF_ILBM
        Image data will be returned in interleaved bitmap format.
        The first entry in lsi_Planes must point to a buffer large
        enough to hold ((lsi_Width+15)/16)*lsi_Height*lsi_Depth bytes.
        In this format only lsi_Y and lsi_Height are valid, pixel
        positioning of data is not allowed.

       OVDF_ALPHA
        This will return the Alpha channel portion of the image. The
        alpha channel is returned as 8bits per pixel with 1 byte per
        pixel. The Alpha channel has the same dimensions as the image
        itself. The first entry in lsi_Planes must point to a buffer
        large enough to hold lsi_Width*lsi_Height bytes.

       OVDF_STENCIL
        Return the stencil data for the image. This function will
        return a single bitplane of data. The first entry of
        lsi_Planes point to a buffer large enough to hold
        ((lsi_Width+15)/16)*lsi_Height bytes.
        In this format only lsi_Y and lsi_Height are valid, pixel
        positioning of data is not allowed.

   OVCMD_GETPALETTE
    If the image is a palette mapped image then the palette will be
    copied into the buffer specified by lsi_Address. This will be an
    array of RGB triplets. If the image is not palette mapped then
    lsi_Result will be FALSE. The buffer must be atleast 736 bytes.

   OVCMD_GETCLUT
    If the image is 24bit this function will copy the colour
    lookup table for the image into the buffer specified by
    lsi_Address. The colour lookup table contains 256 entries
    of RGB tripletes. This is actually an interleaved format
    of 3 seperate 256 entry lookup tables, one for Red, Green
    and Blue. If the image does not have a CLUT (i.e. is palette
    mapped) then lsi_Result will be FALSE.

   OVCMD_GETTHUMBNAIL
    Get the thumbnail data for the image. This will return a pointer
    to a buffer which containing the thumbnail image. The image is
    48x30 in lores OpalVision bitplane format. The total size of this
    image is 12x30x12 or 4320 bytes.

   OVCMD_ERROR
    Report to the host application that an error occured during the save.
    If OpalPaint is the host, the error will be reported to the user
    and the save aborted. The allowable error codes are defined in
    loadsave.h.

   OVCMD_DONE
    Report to the host application that the save has completed.


The  following  command  type  are  host  application  specific, these
commands are available if OpalPaint is the host.  If the host does not
support  these  commands,  the  default  value  as  specified  will be
returned.

   OVCMD_USERMESSAGE
    Report a message to the user. lsi_Address should be a pointer to
    a null terminated string. In the case of OpalPaint a requester will
    appear containing the message string and an OK gadget, the command
    will return when the user closes the requester (this also supports
    the '\n' sequence for specifying mulitple lines of text, note that
    in C this must be specified as \\n). If this command is not supported
    it will return immediately.

   OVCMD_ASKUSER
    This command will ask the user for a boolean (yes/no or OK/Cancel)
    result. The parameters are the same as OVCMD_USERMESSAGE and the
    returned result will be in lsi_Result. In the case of OpalPaint
    a requester will appear with an OK and CANCEL gadget. If this command
    is not available, TRUE will be returned immediately.

   OVCMD_PERCENTAGE
    This command is used to let the host application know the percentage
    of the save that has been performed. OpalPaint will display this
    value in the menu bar to give the user an indication of how things
    are going. lsi_Address should contain a pointer to a _short_ string
    that will appear in the menu bar, this string should be less than
    7 characters. lsi_Result should be a value from 0 to 100 specifying
    the percentage value. If this command is not available it will
    be ignored and returns immediately. It is suggested that you use
    this command as it is very informative to the user.

   OVCMD_BUILDREQUEST
    This gives access to OpalPaint's general purpose requester builder
    function. lsi_Address should contain a pointer to a taglist array.
    Using this function you can build your own requesters and get user
    parameters directly, see the documentation on Build_Request() for
    more information. lsi_Result will be TRUE if the user hit OK or
    FALSE if the user hit CANCEL. If this function is not available
    TRUE will be returned immediately.



            LOADER MODULES

When  a Loader module initialises itself it must create a message port
which  will  be used to communicate with the host program.  The naming
convention  for  this  port will include a brief name of the format or
purpose  of  the module suffixed with "_Loader" some examples would be
"Tiff_Loader", "FrameGrab_Loader".

Once  this  message port has been created you must add yourself to the
current  list  of  active loader modules, to do this you must open the
opal.library and issue the following command:

    AddOVLoader (LoaderName,LoaderPort,Flags)

'LoaderName'  will  normally  be  the  portname  without the "_Loader"
suffix.  This name will be used to identify the loader both internally
within  applications  and  also to the user in programs like OpalPaint
which give a list of the currently available loader modules.

'LoaderPort' is a pointer to the message port created earlier.

'Flags' are currently unused.

Once  the module has been added to the system, it should then wait for
messages  to  arrive at it's message port.  One of 4 possible messages
can arrive.

   OVCMD_FORMATCHECK
    This command is asking your module to check the format of a
    file being loaded, if the format is not known you should
    set lsi_Result to FALSE. If the format is known to the module
    you should return the image details in lsi_Width, lsi_Height,
    lsi_Depth and lsi_Resolution. Also the components of the image
    available should be returned in lsi_Flags, this can be any
    combination of LSIF_HASIMAGE, LSIF_HASSTENCIL and LSIF_ALPHA.

    Specifying an image resolution in lsi_Resolution is optional,
    if you have resolution information then fill in this entry
    with the standard opalvision flags (i.e. HIRES24,ILACE24,
    OVERSCAN24), and set the LSIF_RESVALID flags in lsi_Flags.
    If you do not specify a resolution then the host will pick
    an acceptable resolution based on the image size.

    To enable you to perform the format identification, the first
    section of the file is contained in a buffer pointed to by
    lsi_Address, the size of this buffer is in lsi_DataLength
    (this is 2K in the current implementation), this is useful
    to check header information. Also lsi_FileName can be used
    to check the file extension (to check for '.gif' for example).
    If this is still not enough, the file can be read directly
    using the supplied file handle.

    The OVCMD_FORMATCHECK command is used for the intelligent loader
    in OpalPaint and the library, this way when it attempts to load
    an unknown file it can poll all the available loaders to see if
    any can read the format.

    NOTE 1: There are basically 2 types of loaders. The first type
    load images from files and take part in the intelligent loader
    polling sequence, these loaders have the OVLF_NEEDFILENAME
    set (set in the AddOVLoader() call). The second type do not
    require a file name and do not participate in the polling, this
    type does not have the OVLF_NEEDFILENAME flag set. The second
    type is used for a framegraber or scanner of similar type
    device. This type will only receive an OVCMD_FORMATCHECK when
    they are specifically selected by the user, and hence should
    fill in the image size and return TRUE when the
    OVCMD_FORMATCHECK command is received.

    NOTE 2: After receiving the OVCMD_FORMATCHECK, you may issue
    an OVCMD_ASKUSER, OVCMD_ERROR, OVCMD_DONE, OVCMD_USERMESSAGE
    or OVCMD_BUILDREQUEST before replying to the OVCMD_FORMATCHECK.
    This allows you to bring up a requester asking for the screen
    size to load, before relaying this information to the host, this
    will be necessary for framegrabber/scanner type modules.


   OVCMD_LOADIMAGE
    This command tells the loader to perform the load, you will
    recieve this command after you returned TRUE to a OVCMD_FORMATCHECK
    command. Once this is received you should reply to the message and
    perform the load.

   OVCMD_SETPARAMETERS
    This command is used to set specific parameters for your
    module, the parameters will be a text string pointed to by
    lsi_Address. This is a single text string so that the parameters
    can be passed via ARexx or any other application. This would for
    instance be called after the following Arexx command was issued
    to OpalPaint:

    Loader JPEG Smoothing=On

    The  string 'Smoothing=On' would then be passed to the JPEG
    loader module via  the  OVCMD_SETPARAMTERS command to enable
    cross block smoothing. The format of the parameters is completely
    up to your own requirements, you should of course make the
    allowable parameters known in the documentation for your module.

   OVCMD_EXPUNGE
    If you receive This command you should remove yourself from the
    active list of loader modules using RemOVLoader() opal.library
    function, cleanup all resources and exit.



To  load the image you first need to find the message port of the Host
application  performing  the  load,  this  port  will  always be named
"OVLoader_Port"  which  is defined in the header file as OVLOADERPORT.
Once  this port has been found you can then issue commands back to the
host  so  that  the  actual  image  data can be sent to the host.  The
following commands are currently supported:


   OVCMD_SENDDATA
    Send image data to the host application. lsi_X, lsi_Y denotes the
    position within the image where you wish to put the image data
    from (i.e. Top-Left), and lsi_Width and lsi_Height defines the
    size of the data in the supplied buffers. Note that some data formats
    do not support a non-zero x or a width less than the image width.

    The actual format of the image data is specified in lsi_SubType
    and can be any of the following formats:

       OVDF_PLANAR
        Standard bitplane format. lsi_Planes must contain pointers
        to enough bitplanes to hold the data, the depth of the data
        is given in lsi_Depth. In this format only lsi_Y and
        lsi_Height are valid, pixel positioning of data is not
        allowed.

       OVDF_RGB
        This format is 3 byte planes of Red, Green and Blue.
        The first 3 entries in lsi_Planes must point to buffers
        containing lsi_Width*lsi_Height bytes.

       OVDF_GREY
        This format is grey scale image data. Each pixel is defined
        using a single byte per pixel giving 8bit grey scale.
        The first entry in lsi_Planes must point to a buffer
        containing lsi_Width*lsi_Height bytes.

       OVDF_ILBM
        This format is interleaved bitmap format. The first entry in
        lsi_Planes must point to a buffer containing
        ((lsi_Width+15)/16)*lsi_Height*lsi_Depth bytes.
        In this format only lsi_Y and lsi_Height are valid, pixel
        positioning of data is not allowed.

       OVDF_ALPHA
        This format is the Alpha channel portion of the image. The
        alpha channel is defined as 8bits per pixel with 1 byte per
        pixel. The Alpha channel has the same dimensions as the image
        itself. The first entry in lsi_Planes must point to a buffer
        containing lsi_Width*lsi_Height bytes.

       OVDF_STENCIL
        Send the stencil data for the image. This function will
        send a single bitplane of data. The first entry of
        lsi_Planes point to a buffer containing
        ((lsi_Width+15)/16)*lsi_Height bytes.
        In this format only lsi_Y and lsi_Height are valid, pixel
        positioning of data is not allowed.

   OVCMD_SETPALETTE
    If the image is a palette mapped image then the palette should
    be sent to the host using this command. lsi_Address should point
    to a buffer holding the palette. This size of the palette should
    be dependent on the depth of the image (i.e. 2^Depth). The format
    of the palette is RGB tripletes. The palette data MUST be sent
    before the image data so that remapping to 24bit can be performed
    if necessary.

   OVCMD_SETCLUT
    If the image is 24bit this function can be used to set the
    Colour LookUp Table for the image. A pointer to the CLUT
    data is passed in lsi_Address. The CLUT should contain
    256 entries of RGB tripletes.

   OVCMD_ERROR
    Report to the host application that an error occured during the load.
    In OpalPaint is the host, the error will be reported to the user
    and the load aborted. The allowable error codes are defined in
    loadsave.h.

   OVCMD_DONE
    Report to the host application that the load has completed.


The  following  command  type are host application specific, these commands
are available if OpalPaint is the host.  If the host does not support these
commands, the default value as specified will be returned.


   OVCMD_USERMESSAGE
    Report a message to the user. lsi_Address should be a pointer to
    a null terminated string. In the case of OpalPaint a requester will
    appear containing the message string and an OK gadget, the command
    will return when the user closes the requester (this also supports
    the '\n' sequence for specifying mulitple lines of text, note that
    in C this must be specified as \\n). If this command is not supported
    it will return immediately.

   OVCMD_ASKUSER
    This command will ask the user for a boolean (yes/no or OK/Cancel)
    result. The parameters are the same as OVCMD_USERMESSAGE and the
    returned result will be in lsi_Result. In the case of OpalPaint
    a requester will appear with an OK and CANCEL gadget. If this command
    is not available, TRUE will be returned immediately.

   OVCMD_PERCENTAGE
    This command is used to let the host application know the percentage
    of the load that has been performed. OpalPaint will display this
    value in the menu bar to give the user an indication of how things
    are going. lsi_Address should contain a pointer to a _short_ string
    that will appear in the menu bar, this string should be less than
    7 characters. lsi_Result should be a value from 0 to 100 specifying
    the percentage value. If this command is not available it will
    be ignored and returns immediately. It is suggested that you use
    this command as it is very informative to the user.

   OVCMD_BUILDREQUEST
    This gives access to OpalPaint's general purpose requester builder
    function. lsi_Address should contain a pointer to a taglist array.
    Using this function you can build your own requesters and get user
    parameters directly, see the documentation on Build_Request() for
    more information. lsi_Result will be TRUE if the user hit OK or
    FALSE if the user hit CANCEL. If this function is not available
    TRUE will be returned immediately.





                    Martin Boyd, Opal Technology.


   If you have any questions I am contactable at (in order of preference):

   OpalVision BBS [phone]  'MartinB'
   Internet:  [e-mail]
   Bix:  mboyd